Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated #142677

GuillaumeGomez · 2025-06-18T15:00:31Z

Follow-up of #142601.

Tested it locally with: BASE_COMMIT=1bb335244c311a07cee165c28c553c869e6f64a9 src/ci/docker/host-x86_64/mingw-check-1/validate-rustdoc-json-format-version-update.sh (where BASE_COMMIT value was the commit before I made a wrong change with the FORMAT_VERSION update).

This is a first version. I plan to send a follow-up to also ensure that FORMAT_VERSION is updated if any code change is done in rustdoc-json-types. For that I just need to check that a line not starting with / and not an empty line was updated. Fun times with grep ahead. :')

cc @aDotInTheVoid
r? @nnethercote

rustbot · 2025-06-18T15:00:36Z

nnethercote is not on the review rotation at the moment.
They may take a while to respond.

Kobzol · 2025-06-18T15:04:34Z

Could this be a tidy check instead? It's better to have these things in one centralized place in Rust, rather than scattered around in random bash scripts.

GuillaumeGomez · 2025-06-18T15:06:10Z

I guess? Didn't even realize that I could do the same in rust much more easily. ^^'

GuillaumeGomez · 2025-06-18T15:29:41Z

Moved it to tidy. I'll do the same with the other bash tidy check I added.

GuillaumeGomez · 2025-06-18T15:30:21Z

Oh also:

r? @Kobzol

Kobzol

I guess it could also work locally, but it's always a PITA to figure out a diff vs master, so this is fine. Could you please try to break the CI job in this PR to see if it works on PR CI?

src/tools/tidy/src/rustdoc_json.rs

rustbot · 2025-06-19T11:22:41Z

rustdoc-json-types is a public (although nightly-only) API. If possible, consider changing src/librustdoc/json/conversions.rs; otherwise, make sure you bump the FORMAT_VERSION constant.

cc @CraftSpider, @aDotInTheVoid, @Enselic, @obi1kenobi

Kobzol · 2025-06-19T12:02:35Z

2025-06-19T11:27:57.5354234Z [TIMING] core::build_steps::tool::Tidy { compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu, forced_compiler: false }, target: x86_64-unknown-linux-gnu } -- 0.000
2025-06-19T11:27:57.5354975Z fmt check
2025-06-19T11:28:04.5397272Z fmt: checked 6074 files
2025-06-19T11:28:05.0397217Z tidy check
2025-06-19T11:28:24.2535092Z Running eslint on rustdoc JS files
2025-06-19T11:28:29.4054908Z tidy: Skipping binary file check, read-only filesystem
2025-06-19T11:28:36.0337263Z removing old virtual environment
2025-06-19T11:28:36.0359346Z creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'venv'
2025-06-19T11:28:36.0843019Z creating virtual environment at '/checkout/obj/build/venv' using 'python3.10' and 'virtualenv'
2025-06-19T11:28:37.6050421Z Requirement already satisfied: pip in ./build/venv/lib/python3.10/site-packages (25.1.1)
2025-06-19T11:28:38.8879878Z linting python files
2025-06-19T11:28:39.0477863Z All checks passed!
2025-06-19T11:28:39.0488259Z checking python file formatting
2025-06-19T11:28:39.1812151Z 28 files already formatted
2025-06-19T11:28:39.1822499Z checking C++ file formatting
2025-06-19T11:28:41.0313008Z x.py completions check

Looks like the check didn't run, hmm. Probably adding some logging before the return; statements would be useful, to figure out why. And also printing the output of git diff.

GuillaumeGomez · 2025-06-19T12:52:46Z

It's because BASE_COMMIT is not set in tidy. Changing that.

aDotInTheVoid

Conceptually this change makes sense and is good.

This is a first version. I plan to send a follow-up to also ensure that FORMAT_VERSION is updated if any code change is done in rustdoc-json-types. For that I just need to check that a line not starting with / and not an empty line was updated.

I worry that this could still have false positives. E.g. #142642 touches non-comments in src/rustdoc-json-types, but doesn't need to bump the FORMAT_VERSION

aDotInTheVoid · 2025-06-19T17:24:41Z

src/rustdoc-json-types/lib.rs

@@ -38,7 +38,7 @@ pub type FxHashMap<K, V> = HashMap<K, V>; // re-export for use in src/librustdoc
 // are deliberately not in a doc comment, because they need not be in public docs.)
 //
 // Latest feature: Pretty printing of inline attributes changed
-pub const FORMAT_VERSION: u32 = 48;
+pub const FORMAT_VERSION: u32 = 49;


This 48->49 change should be reverted before merging.

src/tools/tidy/src/main.rs

src/tools/tidy/src/rustdoc_json.rs

…y updated

GuillaumeGomez · 2025-06-20T13:50:05Z

Check is failing as expected so removed the failing commit. Should be now.

Kobzol

Two nits, otherwise looks good.

Kobzol · 2025-06-20T13:56:13Z

src/tools/tidy/src/rustdoc_json.rs

+    ) {
+        Ok(Some(commit)) => commit,
+        Ok(None) => {
+            *bad = true;


Could you please only set *bad here and below on CI (if CiEnv::current() is CI)? For some users get_closest_upstream_commit might not return anything, e.g. if they have a shallow checkout. Yes, this is all sadly very annoying.. :D

I keep discovering new cases to handle 😆

Kobzol · 2025-06-20T13:57:01Z

src/tools/tidy/src/rustdoc_json.rs

+                *bad = true;
+                if latest_feature_comment_updated {
+                    eprintln!(
+                        "error: `Latest feature` comment was updated whereas `FORMAT_VERSION` wasn't"


Although people will probably be able to infer it, I think it would be nice if the error message contained the filename that should be fixed, otherwise the error can be quite opaque.

GuillaumeGomez · 2025-06-20T14:13:35Z

Applied your suggestions. Thanks a lot, learned a lot with this PR!

Only emit git errors if we are in CI environment

Kobzol · 2025-06-20T17:17:37Z

Yeah, there's really a lot to learn here 😆 Thanks!

@bors r+ rollup

bors · 2025-06-20T17:17:40Z

📌 Commit 0fc9507 has been approved by Kobzol

It is now in the queue for this repository.

rustbot assigned nnethercote Jun 18, 2025

rustbot added A-testsuite Area: The testsuite used to check the correctness of rustc S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. T-infra Relevant to the infrastructure team, which will review and decide on the PR/issue. labels Jun 18, 2025

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the check-format-version-update branch from 23e5243 to 5d9e058 Compare June 18, 2025 15:29

rustbot added A-tidy Area: The tidy tool T-bootstrap Relevant to the bootstrap subteam: Rust's build system (x.py and src/bootstrap) labels Jun 18, 2025

rustbot assigned Kobzol and unassigned nnethercote Jun 18, 2025

GuillaumeGomez mentioned this pull request Jun 18, 2025

Rewrite inline attribute parser to use new infrastructure and improve diagnostics for all parsed attributes #138165

Merged

Kobzol reviewed Jun 19, 2025

View reviewed changes

src/tools/tidy/src/rustdoc_json.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the check-format-version-update branch from 5d9e058 to 43d18cf Compare June 19, 2025 11:22

rustbot added the A-rustdoc-json Area: Rustdoc JSON backend label Jun 19, 2025

GuillaumeGomez force-pushed the check-format-version-update branch from 76cea70 to 122cf96 Compare June 19, 2025 15:04

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the check-format-version-update branch from 122cf96 to c352ab5 Compare June 19, 2025 15:12

aDotInTheVoid reviewed Jun 19, 2025

View reviewed changes

Kobzol reviewed Jun 19, 2025

View reviewed changes

src/tools/tidy/src/main.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the check-format-version-update branch from c352ab5 to 5c4daf1 Compare June 20, 2025 11:49

Kobzol reviewed Jun 20, 2025

View reviewed changes

src/tools/tidy/src/rustdoc_json.rs Show resolved Hide resolved

src/tools/tidy/src/rustdoc_json.rs Outdated Show resolved Hide resolved

GuillaumeGomez force-pushed the check-format-version-update branch from 5c4daf1 to 9cccf1e Compare June 20, 2025 12:50

Add CI check to ensure that rustdoc JSON FORMAT_VERSION is correctl…

2180503

…y updated

GuillaumeGomez force-pushed the check-format-version-update branch from fee5757 to 115523e Compare June 20, 2025 13:05

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the check-format-version-update branch from 5efb3f8 to ae4dbd4 Compare June 20, 2025 13:24

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the check-format-version-update branch from ae4dbd4 to cb6460f Compare June 20, 2025 13:31

This comment has been minimized.

Sign in to view

GuillaumeGomez force-pushed the check-format-version-update branch from cb6460f to aa1b8eb Compare June 20, 2025 13:40

This comment has been minimized.

Sign in to view

GuillaumeGomez added 2 commits June 20, 2025 15:49

Generate base commit in rustdoc_json tidy checks

bbe8a2a

Pass src_path to rustdoc_json tidy check

6367694

GuillaumeGomez force-pushed the check-format-version-update branch from aa1b8eb to 6367694 Compare June 20, 2025 13:49

Kobzol reviewed Jun 20, 2025

View reviewed changes

This comment has been minimized.

Sign in to view

Improve error message for rustdoc_json_types tidy check

0fc9507

Only emit git errors if we are in CI environment

GuillaumeGomez force-pushed the check-format-version-update branch from 989fd9d to 0fc9507 Compare June 20, 2025 14:22

bors added S-waiting-on-bors Status: Waiting on bors to run and complete tests. Bors will change the label on completion. and removed S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Jun 20, 2025

Add CI check to ensure that rustdoc JSON FORMAT_VERSION is correctly updated #142677

Are you sure you want to change the base?

Add CI check to ensure that rustdoc JSON FORMAT_VERSION is correctly updated #142677

Conversation

GuillaumeGomez commented Jun 18, 2025

Uh oh!

rustbot commented Jun 18, 2025

Uh oh!

Kobzol commented Jun 18, 2025

Uh oh!

GuillaumeGomez commented Jun 18, 2025

Uh oh!

This comment has been minimized.

GuillaumeGomez commented Jun 18, 2025

Uh oh!

GuillaumeGomez commented Jun 18, 2025

Uh oh!

Kobzol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

rustbot commented Jun 19, 2025

Uh oh!

Kobzol commented Jun 19, 2025

Uh oh!

GuillaumeGomez commented Jun 19, 2025

Uh oh!

This comment has been minimized.

aDotInTheVoid left a comment

Choose a reason for hiding this comment

Uh oh!

aDotInTheVoid Jun 19, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

GuillaumeGomez commented Jun 20, 2025

Uh oh!

Kobzol left a comment

Choose a reason for hiding this comment

Uh oh!

Kobzol Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

Kobzol Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez Jun 20, 2025

Choose a reason for hiding this comment

Uh oh!

GuillaumeGomez commented Jun 20, 2025

Uh oh!

This comment has been minimized.

Kobzol commented Jun 20, 2025

Uh oh!

bors commented Jun 20, 2025

Uh oh!

Uh oh!

Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated #142677

Add CI check to ensure that rustdoc JSON `FORMAT_VERSION` is correctly updated #142677